3D Graphics Programming with QuickDraw 3D 1.5.4

Creating and Managing Attribute Sets

QuickDraw 3D provides a number of routines for creating and managing attribute sets.

Q3AttributeSet_New

You can use the Q3AttributeSet_New function to create an attribute set.



 
TQ3AttributeSet Q3AttributeSet_New (void);

DESCRIPTION

The Q3AttributeSet_New function returns, as its function result, a new empty attribute set. If Q3AttributeSet_New fails, it returns NULL .

Q3AttributeSet_Add

You can use the Q3AttributeSet_Add function to add an attribute to an attribute set.



 
TQ3Status Q3AttributeSet_Add (

                     TQ3AttributeSet attributeSet, 

                     TQ3AttributeType type, 

                     const void *data);

attributeSet: An attribute set.
type: An attribute type.
data: A pointer to the attribute's data.

DESCRIPTION

The Q3AttributeSet_Add function adds the attribute specified by the type and data parameters to the attribute set specified by the attributeSet parameter. The attribute set must already exist when you call Q3AttributeSet_Add . If that attribute set already contains an attribute of the specified type, Q3AttributeSet_Add replaces that attribute with the one specified by the type and data parameters. Note that the attribute data is copied into the attribute set. Accordingly, you can reuse the data parameter once you have called Q3AttributeSet_Add .

Q3AttributeSet_Contains

You can use the Q3AttributeSet_Contains function to determine whether an attribute set contains an attribute of a specific type.



 
TQ3Boolean Q3AttributeSet_Contains (

                     TQ3AttributeSet attributeSet, 

                     TQ3AttributeType attributeType);

attributeSet: An attribute set.
attributeType: An attribute type.

DESCRIPTION

The Q3AttributeSet_Contains function returns, as its function result, a Boolean value that indicates whether the attribute set specified by the attributeSet parameter contains (kQ3True ) or does not contain (kQ3False ) an attribute of the type specified by the attributeType parameter.

Q3AttributeSet_Get

You can use the Q3AttributeSet_Get function to get the data associated with an attribute in an attribute set.



 
TQ3Status Q3AttributeSet_Get (

                     TQ3AttributeSet attributeSet, 

                     TQ3AttributeType type, 

                     void *data);

attributeSet: An attribute set.
type: An attribute type.
data: On entry, a pointer to a structure large enough to hold the attribute data associated with attributes of the specified type. On exit, a pointer to the attribute data of the attribute having the specified type.

DESCRIPTION

The Q3AttributeSet_Get function returns, in the data parameter, the data currently associated with the attribute whose type is specified by the type parameter in the attribute set specified by the attributeSet parameter. If no attribute of that type is in the attribute set, Q3AttributeSet_Get returns kQ3Failure and posts the error kQ3ErrorAttributeNotContained .

If you pass the value NULL in the data parameter, no data is copied back to your application.

ERRORS

kQ3ErrorAttributeNotContained

Q3AttributeSet_GetNextAttributeType

You can use the Q3AttributeSet_GetNextAttributeType function to iterate through all the attributes in an attribute set.



 
TQ3Status Q3AttributeSet_GetNextAttributeType (

                     TQ3AttributeSet source, 

                     TQ3AttributeType *type);

source: An attribute set.
type: On entry, an attribute type. On exit, the attribute type of the attribute that immediately follows that attribute in the attribute set.

DESCRIPTION

The Q3AttributeSet_GetNextAttributeType function returns, in the type parameter, the attribute type of the attribute that immediately follows the attribute having the type specified by the type parameter in the attribute set specified by the source parameter. To get the type of the first attribute in the attribute set, pass kQ3AttributeTypeNone in the type parameter. Q3AttributeSet_GetNextAttributeType returns kQ3AttributeTypeNone when it has reached then end of the list of attributes.

Q3AttributeSet_Empty

You can use the Q3AttributeSet_Empty function to empty an attribute set of all its attributes.



 
TQ3Status Q3AttributeSet_Empty (TQ3AttributeSet target);

target: An attribute set.

DESCRIPTION

The Q3AttributeSet_Empty function removes all the attributes currently in the attribute set specified by the target parameter.

Q3AttributeSet_Clear

You can use the Q3AttributeSet_Clear function to remove an attribute of a certain type from an attribute set.



 
TQ3Status Q3AttributeSet_Clear (

                     TQ3AttributeSet attributeSet, 

                     TQ3AttributeType type);

attributeSet: An attribute set.
type: An attribute type.

DESCRIPTION

The Q3AttributeSet_Clear function removes the attribute whose type is specified by the type parameter from the attribute set specified by the attributeSet parameter.

Q3AttributeSet_Submit

You can use the Q3AttributeSet_Submit function to submit an attribute set in immediate mode.



 
TQ3Status Q3AttributeSet_Submit (

                     TQ3AttributeSet attributeSet, 

                     TQ3ViewObject view);

attributeSet: An attribute set.
view: A view.

DESCRIPTION

The Q3AttributeSet_Submit function submits the attribute set specified by the attributeSet parameter into the view specified by the view parameter.

SPECIAL CONSIDERATIONS

You should call Q3AttributeSet_Submit only in a submitting loop.

Q3AttributeSet_Inherit

You can use the Q3AttributeSet_Inherit function to configure an attribute set so that it contains all the attributes of a child set together with all the attributes inherited from a parent set.



 
TQ3Status Q3AttributeSet_Inherit (

                     TQ3AttributeSet parent, 

                     TQ3AttributeSet child, 

                     TQ3AttributeSet result);

parent: An attribute set.
child: An attribute set.
result: On entry, an attribute set. On exit, an attribute set that contains all the attributes in the specified child set together with all the attributes inherited from the specified parent set.

DESCRIPTION

The Q3AttributeSet_Inherit function returns, in the result parameter, an attribute set that merges attributes from the attribute sets specified by the child and parent parameters. The resulting set contains all the attributes in the child set together with all those in the parent set having an attribute type that is not contained in the child attribute set.

If the specified child and parent attribute sets contain any custom attribute types, Q3AttributeSet_Inherit uses the custom type's kQ3MethodTypeAttributeCopyInherit custom method. See the chapter "QuickDraw 3D Objects" for complete information on custom element types.